home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / prog_c / recio214.zip / DESIGN.TXT < prev    next >
Text File  |  1996-06-14  |  18KB  |  397 lines
  1.     Title: RECIO DESIGN AND DEVELOPMENT NOTES
  2. Copyright: (C) 1994-1996, William Pierpoint
  3.   Version: 2.14
  4.      Date: June 14, 1996
  5.  
  6.  
  7.  
  8. 1.0 DATA STRUCTURES
  9.  
  10. 1.1 REC structure for each record stream
  11.  
  12.     * defined in recio.h.
  13.     * 3 (!dos) or 4 (dos) static RECs for recin, recout, etc (included in
  14.       ROPEN_MAX count).
  15.     * allocate dynamic array of RECs dimensioned to ROPEN_MAX-NREC in ropen().
  16.     * Each REC has two associated buffers:
  17.       1) record string buffer containing current record;
  18.          allocate when first record read;
  19.          reallocate if record becomes larger.
  20.       2) field string buffer containing current field;
  21.          allocate when first field read;
  22.          reallocate if field becomes larger.
  23.     * deallocate dynamic RECs and associated buffers in rclose() and
  24.       rcloseall() if all record streams closed; deallocate associated
  25.       buffers for recin with an exit function registered with atexit().
  26.  
  27.  
  28. 1.2 REC r_flags assignments
  29.  
  30.     Bit        Description
  31.    -----    -------------------------------------------------------------
  32.      0        If clear, colno start at 0; if set, colno start at 1
  33.      1      if clear, read mode; if set, write/append mode
  34.      2      if clear, current field not quoted by r_txtch;
  35.             if set, current field quoted by r_txtch.
  36.     3-6     Reserved for future use.
  37.      7        If clear, EOF not reached; if set, EOF reached
  38.     8-11    If clear, no error; else rerror number
  39.    12-15    if clear, no warning; else rwarning number
  40.  
  41.  
  42. 1.3 Accessing REC Members and Associated Buffers
  43.  
  44.     How do I
  45.     * access the name of the record stream?           rnames()
  46.     * access the current context number?              rcxtno()
  47.     * access the current record number?               rrecno()
  48.     * access the current field number?                rfldno()
  49.     * access the current column number?               rcolno()
  50.     * access the record string buffer?                rrecs()
  51.     * access the field string buffer?                 rflds()
  52.     * determine the number of fields in a record?     rnumfld()
  53.     * determine if column numbers start at 0 or 1?    rbegcolno()
  54.     * determine if the current field was quoted?      ristxtfld()
  55.     * determine if there are more records left?       reof()
  56.     * determine if there is an error on the stream?   rerror()
  57.     * determine if there is a warning on the stream?  rwarning()
  58.     * access the error message for the stream?        rerrstr()
  59.     * force an error on a record stream?              rseterr()
  60.     * clear an error on a record stream?              rclearerr()
  61.     * scan the record buffer more than once?          rresetrec()
  62.     * increase the size of the record string buffer?  rsetrecsiz()
  63.     * increase the size of the field string buffer?   rsetfldsiz()
  64.     * replace the data in the field string buffer?    rsetfldstr()
  65.     * replace the data in the record string buffer?   rsetrecstr()
  66.     * get/set position of a field in a record?        rgetfldpos()/rsetfldpos()
  67.     * set the field delimiter character?              rsetfldch()
  68.     * set the text delimiter character?               rsettxtch()
  69.     * set the time format string?                     rsettmfmt()
  70.     * set the context number?                         rsetcxtno()
  71.     * set column numbering to start at 0 or 1?        rsetbegcolno()
  72.     * dynamically copy a string?                      scpys()
  73.     * dynamically concatenate a string?               scats()
  74.     * trim white space from the ends of a string?     strims()
  75.  
  76.  
  77.  
  78. 2.0 CODE STRUCTURES
  79.  
  80. 2.1 RECIO Structure Chart
  81.  
  82.     ╔═════════╗                  ╔═════════╗
  83.     ║ rstr.c  ║                  ║ recio.c ║
  84.     ╚════╤════╝                  ╚═╤══╤══╤═╝
  85.          │                         │  │  │
  86.          │    ╔════════╗     input │  │  │ output   ╔════════╗
  87.          └────╢ rget.c ╟───────────┘  │  └──────────╢ rput.c ║
  88.        char   ╚═╤════╤═╝ column       │      char   ╚═╤════╤═╝ column
  89.      delimited  │    │  delimited     │    delimited  │    │  delimited
  90.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  91.     ║ rgetf.c ╟─┤    ├─╢ rcgetf.c ║   │   ║ rputf.c ╟─┤    ├─╢ rcputf.c ║
  92.     ╚═════════╝ │    │ ╚══════════╝   │   ╚═════════╝ │    │ ╚══════════╝
  93.                 │    │                │               │    │
  94.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  95.     ║ rgets.c ╟─┤    ├─╢ rcgets.c ║   │   ║ rputs.c ╟─┤    ├─╢ rcputs.c ║
  96.     ╚═════════╝ │    │ ╚══════════╝   │   ╚═════════╝ │    │ ╚══════════╝
  97.                 │    │                │               │    │
  98.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  99.     ║ rgett.c ╟─┤    ├─╢ rcgett.c ║   │   ║ rputt.c ╟─┤    ├─╢ rcputt.c ║
  100.     ╚═════════╝ │    │ ╚══════════╝   │   ╚═════════╝ │    │ ╚══════════╝
  101.                 │    │                │               │    │
  102.     ╔═════════╗ │    │ ╔══════════╗   │   ╔═════════╗ │    │ ╔══════════╗
  103.     ║ rbget.c ╟─┘    └─╢ rcbget.c ║   │   ║ rbput.c ╟─┘    └─╢ rcbput.c ║
  104.     ╚═════════╝        ╚══════════╝   │   ╚═════════╝        ╚══════════╝
  105.                                       │
  106.                        ╔══════════╗   │   ╔═════════╗        ╔══════════╗
  107.                        ║ rwarn.c  ╟───┴───╢ rerr.c  ╟────────╢  rfix.c  ║
  108.                        ╚════╤═════╝       ╚════╤════╝        ╚══════════╝
  109.                             │                  │
  110.                        ╔════╧═════╗       ╔════╧════╗
  111.                        ║ rwmsg.c  ║       ║ remsg.c ║
  112.                        ╚══════════╝       ╚═════════╝
  113.  
  114.  
  115. 2.2 Callback Error Functions
  116.  
  117.     The callback error function technique used by the RECIO library can
  118.     be applied within your programs to other abstract data types.  For
  119.     abstract data types within the standard C library, you will need to
  120.     write wrapper functions.
  121.  
  122.                                  ╔═════════╗
  123.                                  ║ errnofn ║
  124.                                  ╚════╤════╝
  125.                                       │
  126.                        ┌──────────────┼──────────────┬───── etc
  127.                        │              │              │
  128.                   ╔════╧════╗    ╔════╧════╗    ╔════╧════╗
  129.                   ║ rerrfn  ║    ║ ferrfn  ║    ║ merrfn  ║
  130.                   ╚═════════╝    ╚═════════╝    ╚═════════╝
  131.              REC            FILE          MEMORY
  132.  
  133.  
  134. 2.2.1 Errno Callback Error Function Skeleton [errnofn()]
  135.  
  136.     switch on error number [errno]
  137.     case out of memory [ENOMEM]
  138.     case out of range [ERANGE]
  139.     case out of record or file pointers [EMFILE]
  140.     case permission denied [EACCES]
  141.     case invalid argument [EINVAL]
  142.     default [anything else]
  143.     endcase
  144.  
  145.  
  146. 2.2.2 RECIO Callback Error Function Skeleton [rerrfn(rp)]
  147.  
  148.     if valid record pointer [risvalid(rp)]
  149.         if past end of file [reof(rp)]  (if reof test removed, past EOF will
  150.         else [error number set]           become R_EMISDAT or R_WEMPSTR)
  151.             switch on error number [rerror(rp)]
  152.             case read data errors [R_ERANGE || R_EINVDAT || R_EMISDAT]
  153.             case write data errors [R_ENOPUT]
  154.                 switch on context number [rcxtno(rp)]
  155.                 case RECIN
  156.                     switch field number [rfldno(rp)]
  157.                     case 1 (first field read)
  158.                     case 2 (second field read)
  159.                     ...
  160.                     endcase
  161.                 ...
  162.                 default [missing or unknown context number]
  163.                 endcase
  164.             case out of memory [R_ENOMEM]
  165.             case fatal errors [R_EINVAL || R_EINVMOD]
  166.             default [anything else]
  167.             endcase
  168.         endif
  169.     else [invalid record pointer]
  170.         call error function that handles errno errors [errnofn()]
  171.     endif
  172.  
  173.  
  174. 2.3 RECIO Callback Warning Function Skeleton [rwarnfn(rp)]
  175.  
  176.     if valid record pointer [risvalid(rp)]
  177.         switch on warning number [rwarning(rp)]
  178.         case read data warnings [R_WEMPSTR || R_WTMFMT]
  179.         case write data warnings [R_WWIDTH]
  180.         case code runtime warnings [R_WNOREG]
  181.         default [anything else]
  182.         endcase
  183.     endif
  184.  
  185.  
  186. 2.4 RECIO Field Parsing Algorithm
  187.  
  188. The RECIO library parses a field from an input record according to 
  189. regular expressions that are specified below using PERL programming 
  190. language notation (see the references in section 4.0).  Four cases must 
  191. be considered that depend on whether the field and text delimiters are 
  192. set to whitespace or to something else.  To illustrate the cases below, 
  193. that something else is the comma character for the field delimiter and 
  194. the double quote character for the text delimiter.
  195.  
  196. case 1: fldch = ' '; txtch = ' ';
  197.         \s*(\S*)(\s*(\s|$))
  198.  
  199. case 2: fldch = ','; txtch = ' ';
  200.         ([^,]*)(,|$)
  201.  
  202. case 3: fldch = ' '; txtch = '"'; 
  203.      A: \s*"(([^"]|"[^"]*"|"\S)*"?)("\s*(\s|$))
  204.      B: \s*"(([^"]|"\S)*"?)("\s*(\s|$))
  205.  
  206.         notes: (1) use case 3 when first nonwhitespace character is txtch; 
  207.                    otherwise use case 1.
  208.                (2) use case 3A when txtch is the double quote character;
  209.                    use the form of case 3B for any other nonwhitespace 
  210.                    text delimiter.
  211.  
  212. case 4: fldch = ','; txtch = '"';
  213.      A: \s*"(([^"]|"[^"]*"|"\s*[^,])*"?)("\s*(,|$))
  214.      B: \s*"(([^"]|"\s*[^,])*"?)("\s*(,|$))
  215.  
  216.         notes: (1) use case 4 when first nonwhitespace character is txtch; 
  217.                    otherwise use case 2.
  218.                (2) use case 4A when txtch is the double quote character;
  219.                    use the form of case 4B for any other nonwhitespace 
  220.                    text delimiter.  (Example: "use case "4A", okay?", is 
  221.                    one field using case 4A, but would break after the 
  222.                    first comma if using case 4B.  Case 4A is limited to 
  223.                    double quote characters since other delimiters might 
  224.                    not be used in matching pairs.  For instance, the 
  225.                    single quote character is also used as an apostrophe.)
  226.  
  227. When the parsing algorithm is finished, the field buffer contains the 
  228. equivalent of the PERL variable $1.  The field parsing code can be 
  229. found in the _rfldlen and _rfldstr functions in rget.c.
  230.  
  231.  
  232.  
  233. 3.0 DEVELOPMENT NOTES
  234.  
  235. 3.1 fgets (Microsoft C 5.1)
  236.  
  237. Previous notes of mine indicate that Microsoft's fgets function does not
  238. work correctly when it reads a line of text that consists of only a newline.
  239. However this can be worked around by first setting the string buffer to an
  240. empty string.  If you plan on retaining the newline, you will need to test
  241. this further.  The fgets function is used twice in the rgetrec function.
  242. If porting to Microsoft C, you may need to implement this fix in rget.c:
  243.  
  244.      *rrecs(rp) = '\0';  /* just prior to the first fgets (added v1.20) */
  245.      *str = '\0';        /* just prior to the second fgets */
  246.  
  247.  
  248. 3.2 fopen (Borland C 3.1)
  249.  
  250. fopen() calls __openfp() calls open().  Borland's "Library Reference"
  251. documents error numbers for open(), but not for fopen().  These error
  252. numbers are ENOENT, EMFILE, EACCES, and EINVACC.  Because ropen() screens
  253. the access code, the EINVACC error should not occur from the recio library.
  254.  
  255.  
  256. 3.3 strtol & strtoul (Borland C 3.1)
  257.  
  258. These functions stop consuming input once they overflow, setting ERANGE.
  259. Hence endptr can point into the middle of a sequence of valid characters
  260. having the expected form as given in ANSI X3.159-1989, Sections 4.10.1.5
  261. and 4.10.1.6.  IMHO this characteristic is not in conformance with the
  262. ANSI standard as endptr should only point to the first unrecognized
  263. character or to the terminating null character.  Borland's strtod does
  264. not have this problem.
  265.  
  266. Note that ANSI X3.159-1989 Section 4.10.1.6 allows strtoul (unsigned
  267. long) to have an optional negative sign.  A negative unsigned long?!
  268. Borland 3.1 strtoul converts a negative long to an unsigned number
  269. without error.  But I prefer to trap any negative numbers input to
  270. unsigned fields.  So str2ul is a wrapper function for strtoul that
  271. first tests for a negative number and if one is found, flags the data
  272. as invalid and returns zero.
  273.  
  274. The test suite includes -0 as a data value.  The strtol function traps
  275. this as an ERANGE error and returns the overflow limit.  The rfixi and
  276. rfixl functions substitute zero.
  277.  
  278. 3.4 strtod (Borland C 3.1)
  279.  
  280. Unlike the strtol and strtoul functions, strtod does not clear errno first.
  281. Starting with recio vers. 2.02, errno is cleared before any conversion
  282. where recio code checks the value of errno after the conversion.  It is also
  283. cleared when a record stream is successfully opened.
  284.  
  285. 3.5 mktime (Borland C 3.1)
  286.  
  287. The Borland C 3.1 mktime function has valid range from 1 Jan 1970 00:00:00 
  288. to 19 Jan 2038 03:14:07.  Actual upper limit can vary by a few hours 
  289. depending on the timezone setting.  For EST, upper limit is 18 Jan 2038 
  290. 22:14:07.  When the recio library reads a 2-digit year, it first represents 
  291. it in a struct tm from 1970 to 2069.  The mktime function is then used to 
  292. convert to a time_t.  Hence, when compiled with the Borland C 3.1 compiler, 
  293. the recio library routines fail for any dates beyond 18 or 19 Jan 2038, or 
  294. before 1 Jan 1970.
  295.  
  296. The minimum and maximum values of time_t are controlled by the recio.h
  297. symbolic constants TIME_T_MIN and TIME_T_MAX.  These are used only by 
  298. the time functions in rfix.c.  Borland C 3.1 represents time_t using 
  299. a long.  Thus TIME_T_MIN is set to 0 and TIME_T_MAX is set to LONG_MAX.
  300. LONG_MAX is defined in your compiler's header file limits.h.  You should 
  301. find your compiler's representation of time_t in your compiler's header 
  302. file time.h.
  303.  
  304. 3.6 ltoa and ultoa (ANSI-C)
  305.  
  306. Your ANSI-C compiler might lack the ltoa and ultoa functions as these are 
  307. missing from ANSI X3.159-1989.  These functions convert a long and an
  308. unsigned long to a string.  The recio library uses these functions.  If 
  309. they are missing from your compiler, you can write a simple version of
  310. these functions by using the sprintf function.  The sprintf function limits 
  311. the radix (base) to 8, 10, and 16, but this will probably be adequate for 
  312. most applications.  The prototypes for recio.h are:
  313.  
  314. extern char *ltoa(long l, char *str, int base);
  315. extern char *ultoa(unsigned long ul, char *str, int base);
  316.  
  317. The logical place for the ltoa and ultoa functions is in rput.c next to 
  318. the dtoa function.  The code is as follows:
  319.  
  320. /****************************************************************************/
  321. char *                       /* return pointer to string                    */
  322.     ltoa(                    /* convert long number to string               */
  323.         long   l,            /* number to convert                           */
  324.         char  *str,          /* string buffer to use                        */
  325.         int    base)         /* radix of the number                         */
  326. /****************************************************************************/
  327. {
  328.     switch (base) {
  329.     case 8:
  330.         sprintf(str, "%lo", (unsigned long) l);
  331.         break;
  332.     case 10:
  333.         sprintf(str, "%ld", l);
  334.         break;
  335.     case 16:
  336.         sprintf(str, "%lx", (unsigned long) l);
  337.         break;
  338.     default:   /* error */
  339.         *str = '\0';
  340.         rseterr(NULL, EINVAL);
  341.     }
  342.     return str;
  343. }
  344.  
  345. /****************************************************************************/
  346. char *                       /* return pointer to string                    */
  347.     ultoa(                   /* convert unsigned long number to string      */
  348.         unsigned long  ul,   /* number to convert                           */
  349.         char          *str,  /* string buffer to use                        */
  350.         int            base) /* radix of the number                         */
  351. /****************************************************************************/
  352. {
  353.     switch (base) {
  354.     case 8:
  355.         sprintf(str, "%lo", ul);
  356.         break;
  357.     case 10:
  358.         sprintf(str, "%lu", ul);
  359.         break;
  360.     case 16:
  361.         sprintf(str, "%lx", ul);
  362.         break;
  363.     default:   /* error */
  364.         *str = '\0';
  365.         rseterr(NULL, EINVAL);
  366.     }
  367.     return str;
  368. }
  369.  
  370. In recio.h, the value of NSBUFSIZ is used to dimension the internal string 
  371. buffer that the recio library uses when it calls the ltoa, ultoa, and dtoa 
  372. functions.  This value must be large enough to hold every possible number 
  373. (integral and floating point) without overflowing the string buffer.  In 
  374. determining the value, keep in mind the following points:
  375.  
  376.     * Integral numbers contain more digits as the radix gets smaller.
  377.  
  378.     * Reserve space for the exponent of a floating point number,
  379.       including the 'E'.
  380.  
  381.     * Reserve space for possible sign(s).  Floating point numbers can
  382.       contain two signs, e.g. -1.11E-01.
  383.  
  384.     * Reserve space for the terminating null.
  385.  
  386.     * Valuable information on the representation of numbers is contained 
  387.       in your compiler's header files float.h and limits.h.
  388.  
  389.  
  390. 4.0 REFERENCES
  391.  
  392. Wall, L. and Schwartz, R.L.  Programming Perl.  O'Reilly & Associates,
  393. Sebastopol, CA, 1991, p. 103 ff.
  394.  
  395. Schreiner, A.T. and Friedman, Jr., H.G.  Introduction to Compiler 
  396. Construction with UNIX.  Prentice-Hall, Englewood Cliffs, NJ, 1985, p. 25.
  397.